/*
 * Copyright (C) 2025 Tsingteng MicroSystem
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * @file nci_task.h
 * @brief NCI任务执行器定义，用于NCI模块执行异步任务
 */

#ifndef _NCI_TASK_H_
#define _NCI_TASK_H_

#include "nci_base.h"
#include "message_queue.h"

/**
 * @brief NCI任务事件定义
 *
 * EVT定义规则：
 * - 每个EVT由2 Byte组成，高位为GROUP ID，低位为在此GROUP中的事件ID
 * - 每个Group的EVT定义开始于一个值，如：NCI_TASK_EVT_RW_GROUP = 0x0000，GROUP值不用做模块的具体事件定义
 * - 每个Group的EVT事件从GROUP值之后开始定义，不进行赋值，直接从GROUP值开始递增
 * - 新的Group值定义时，需要重新定义GROUP值，每个模块的GROUP值的高位都手动赋值并相对于上一个GROUP递增
 */
typedef enum {
    /** @brief 读卡模块事件定义开始 */
    NCI_TASK_EVT_RW_GROUP = 0x0000,
    /** @brief TAG发现事件 */
    NCI_TASK_EVT_RW_TAG_DISCOVERED,
    /** @brief TAG激活事件 */
    NCI_TASK_EVT_RW_TAG_ACTIVATED,
    /** @brief TAG丢失事件 */
    NCI_TASK_EVT_RW_TAG_LOSTED,
    /** @brief 停止读卡WATCH DOG线程 */
    NCI_TASK_EVT_RW_WATCH_DOG_STOP,
    /** @brief EE模块事件定义开始 */
    NCI_TASK_EVT_EE_GROUP = 0x0100,
    /** @brief NFCEE STATUS NTF事件 */
    NCI_TASK_EVT_EE_STATUS_NTF,
    /** @brief NFCEE DISCOVERY REQ NTF事件 */
    NCI_TASK_EVT_EE_DISCOVERY_REQ_NTF,
    /** @brief CE模块事件定义开始 */
    NCI_TASK_EVT_CE_GROUP = 0x0200,
    /** @brief 进/离场事件通知 */
    NCI_TASK_EVT_CE_FIELD_INFO,
    /** @brief 激活事件通知 */
    NCI_TASK_EVT_CE_ACTIVATED,
    /** @brief 去激活事件通知 */
    NCI_TASK_EVT_CE_DEACTIVATED,
    /** @brief 发送数据事件通知 */
    NCI_TASK_EVT_CE_DATA,
    /** @brief DATA相关的事件定义开始 */
    NCI_TASK_EVT_DATA_GROUP = 0x0300,
    /** @brief DATA分发事件 */
    NCI_TASK_EVT_DATA_DISPATCH,
    /** @brief Discovery模块相关的事件定义开始 */
    NCI_TASK_EVT_DISC_GROUP = 0x0400,
    /** @brief 去激活 */
    NCI_TASK_EVT_DISC_DEACTIVATE,
    /** @brief 重启Discovery */
    NCI_TASK_EVT_DISC_RESTART_DISCOVERY,
    /** @brief NCI传输层相关的事件定义开始 */
    NCI_TASK_EVT_TRANSPORT_GROUP = 0x0500,
    /** @brief NCI传输层分发事件 */
    NCI_TASK_EVT_TRANSPORT_DISPATCH,
    /** @brief 注入NTF并交由NCI传输层分发处理 */
    NCI_TASK_EVT_TRANSPORT_INJECT_NTF,
    /** @brief NCI私有事件定义开始 */
    NCI_TASK_EVT_PROPRIETARY_GROUP = 0x0600,
    /** @brief EE ACTION上报信息通知 */
    NCI_TASK_EVT_PROPRIETARY_EE_ACTION,
    /** @brief LxDebug等上报信息通知 */
    NCI_TASK_EVT_PROPRIETARY_NOTIFY,
    /** @brief 用于统计NCI任务事件最大数量 */
    NCI_TASK_EVT_MAX,
} tNCI_TASK_EVT;

/**
 * @brief NCI任务执行器初始化函数
 *
 * @return 初始化成功返回NCI_STATUS_OK，否则返回错误码
 */
tNCI_STATUS nci_task_init();
/**
 * @brief NCI任务执行器销毁函数
 *
 * @return 销毁成功返回NCI_STATUS_OK，否则返回错误码
 */
tNCI_STATUS nci_task_deinit();

/**
 * @brief 注册NCI任务
 *
 * @param handle 任务执行器句柄
 * @param cleanup 任务执行器清理函数
 * @param event 需要注册的EVT，选用每个模块的GROUP值进行注册，注册成功后所有此GROUP下的EVT都会分发给handle处理
 *
 * @return 注册成功返回NCI_STATUS_OK，否则返回错误码
 */
tNCI_STATUS nci_task_register(tMQ_HANDLE handle, tMQ_CLEANUP cleanup, tNCI_TASK_EVT event);
/**
 * @brief 注销NCI任务
 *
 * @param num_of_event 本次注销的事件数量
 * @param event 需要注销的EVT，选用每个模块的GROUP值进行注销
 *
 * @return 注销成功返回NCI_STATUS_OK，否则返回错误码
 */
tNCI_STATUS nci_task_unregister(tNCI_TASK_EVT event);
/**
 * @brief 发送NCI任务
 *
 * @note 如果任务发送成功，则会接管args的内存，因此调用者无需再释放
 *
 * @param event 任务事件
 * @param arg1 任务参数1
 * @param arg2 任务参数2
 * @param args 任务参数3
 *
 * @return 发送成功返回NCI_STATUS_OK，否则返回错误码
 */
tNCI_STATUS nci_task_post(tNCI_TASK_EVT event, uint32_t arg1, uint64_t arg2, void *args);
/**
 * @brief 延时发送NCI任务
 *
 * @note 如果任务发送成功，则会接管args的内存，因此调用者无需再释放
 *
 * @param event 任务事件
 * @param arg1 任务参数1
 * @param arg2 任务参数2
 * @param args 任务参数3
 * @param delay 延时时间
 *
 * @return 发送成功返回NCI_STATUS_OK，否则返回错误码
 */
tNCI_STATUS nci_task_post_delay(tNCI_TASK_EVT event, uint32_t arg1, uint64_t arg2, void *args, uint64_t delay);

#endif /* _NCI_TASK_H_ */
